home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The X-Philes (2nd Revision)
/
The X-Philes Number 1 (1995).iso
/
xphiles
/
hp48hor1
/
usrlib.txt
< prev
next >
Wrap
Text File
|
1995-03-31
|
22KB
|
664 lines
Instructions for MS-DOS program "USRLIB"
*****************************************************************
NOTICE
Hewlett-Packard is making the current preliminary version 2.2 of
USRLIB.EXE available to customers free of charge to help them in
HP 48SX application development, under the following conditions:
* The program USRLIB.EXE and the documentation file USRLIB.MAN are
provided "as is," and are subject to change without notice.
Hewlett-Packard Company make no warranty of any kind with regard
to the software or documentation, including, but not limited to,
the implied warranties of merchantability and fitness for a
particular purpose. Hewlett-Packard Company shall not be liable
for any error or for incidental or consequential damages in
connection with the furnishing, performance, or use of this
software and documentation.
* The program and documentation are copyrighted by Hewlett-
Packard. Customers may freely reproduce and distribute this
material. Sale of this material is prohibited without prior
written permission of Hewlett-Packard Company.
* The HP Customer Support department does not support the current
version. Questions, comments, defect reports, etc. should be
directed to the Library Development conference on the HP
Calculator Bulletin Board System. All responses from Hewlett-
Packard will normally be provided through that conference.
* Software converted into libraries by USRLIB.EXE should be tested
and qualified in its library form. Discrepancies between the
execution of the libraries and the execution of the original
source directory contents should be reported via the Bulletin
Board.
Revised versions of the software and documentation will be posted
on the Bulletin Board as they become available. In particular,
future versions will include less cryptic error messages, and
better documention of the output listing information provided by
the program.
Version 2.2 of the program USRLIB.EXE is a preliminary version of
this software. Software compiled into libraries using this
program should be thoroughly tested in its library form prior to
any reproduction or distribution to end users.
*****************************************************************
-1-
1. INTRODUCTION
USRLIB.EXE is an MS-DOS executable file that creates an HP 48
library object from an HP 48 directory. A library is similar to a
directory in that both are collections of named objects. However,
a directory normally resides in main RAM memory and is intended
for continuous modification and execution, whereas a library
contains objects intended for execution only, and can be used from
ROM as readily as from RAM. A directory's objects are organized
in a linked list requiring a sequential search for access; a
library contains an address table that provides rapid execution
access to its individual objects.
1.1 Glossary of Terms
Directory HP48 directory object containing zero or more
variables.
Variable A named object contained within a directory,
accessed by means of a global name.
Library HP 48 library object containing zero or more
library commands. Libraries include a text
title, a Library ID number, and optional
message tables and configuration code that is
executed at system halts.
Library command A named object within a library, which is the
library analog of a directory's variable.
Global name HP 48 global name object, execution of which
executes the object in the corresponding
(global) variable.
XLIB name HP 48 XLIB name object, execution of which
executes the corresponding library command.
An XLIB name plays the role for libraries that
a global name plays for directories.
Library ID A number in the range 0-7FFh that uniquely
identifies a library, and is used as an
argument for HP 48 commands that deal with
libraries as objects. The following ranges
are defined for the ID numbers:
-2-
ID Range Purpose
Hex Decimal
0 - 100 0 - 256
101 - 200 257 - 512 HP ROM-Based Applications
201 - 300 513 - 768 HP RAM-Based Applications
Non-HP Applications
(numbers permanently
assigned by HP)
301 - 600 769 - 1536
601 - 6FF 1537 - 1792
700 - 7FF 1792 - 2047 HP 48SX Command Line Use
1.2 The Source Directory
USRLIB uses an HP 48 directory object as the source file to define
the output library. The source directory may contain any number
of variables, each of which is converted to a library command in
the output library (unless specified otherwise; see $VARS,
$VISIBLE and $HIDDEN, below). The objects in the variables are
translated as necessary so that any global names in the objects
that correspond to variables in the source directory are converted
to XLIB names.
The source directory may contain subdirectories, but in that case
the resulting library will not reflect the structure of the
directory since a library structure is "flat." If separate
subdirectories contain variables with the same name, the uses of
those names within the library will be correct, but the duplicated
names will also be duplicated in the LIBRARY menu. The names of
the subdirectories themselves are not translated to library
commands, and any use of those names in any of the other variables
will result in an error during execution of USRLIB.
The directory may also include the following special variables:
$ROMID Contains a real or binary number object representing
the Library ID that is to be given to the library.
This can be overridden by specifying -r<romid> on the
command line. The ID should be in the range 769 -
1792 (301h - 6FFh).
The -r option must be specified from the command line
if no $ROMID is used.
$TITLE Contains a string to be used as the name of the
library. This can be overridden by specifying -t<title>
on the command line. The first (up to) 5 characters
-3-
of the title are used for the LIBRARY menu label; the
first 22 characters are displayed by REVIEW.
$CONFIG Contains an object to be executed at configuration
time. If no $CONFIG variable is present, no
configuration entry will be generated. In the current
version of USRLIB, $CONFIG is also translated to a
library command; to prevent this, it $CONFIG should be
declared as hidden (see below).
Note: the configuration code can generally NOT be
written in user-accessible commands. Simple programs
such as << 123 ATTACH >> are OK, but more complicated
programs should take care to leave the stack
unchanged, and be sure NOT TO ERROR.
$MESSAGE Contains a list of names of variables that contain
strings to be combined into a message table. The
message numbers correspond to the list positions.
If no $MESSAGE is present, no message table will be
generated.
$VISIBLE Contains a list of names of variables to be converted
to user-accessible library commands.
By default, all variables will be translated to
library commands. When the $VISIBLE list is present,
only the names in this list are used as XLIB name
table entries in the library. An empty list is
allowed, meaning that no XLIB name entries are
created.
$HIDDEN Contains a list of names of variables that are to be
converted to null-named objects in the library, and so
hidden from the library user.
When the $HIDDEN list is present, those names listed
are not entered in the library XLIB name table. If
both $VISIBLE and $HIDDEN are present, only the
$HIDDEN list will be used.
$VARS Contains a list of variables that should remain RAM-
based, i.e., the stored objects are not included in
the library, and no XLIB name entries are made for
their names. All other variables in the source
-4-
directory names are included as library commands.
Multiple instances are permitted of the declaration variables
$VARS, $HIDDEN, and $VISIBLE variables, in various subdirectories
of the source directory. A particular variable is declared as a
RAM variable, hidden, etc., if its name is entered in any of the
relevant declaration variables anywhere in the current path
defined by the variable's location. That is, a variable XXX found
in any subdirectory will be hidden if XXX is in a list stored in
$HIDDEN in the top level of the source directory; but YYY in the
top level will not be hidden even if YYY is present in a $HIDDEN
list in a subdirectory.
Not all program objects that execute correctly from global
variables are directly convertible into libraries. In general, no
checks can be made for such errors, and USRLIB does not attempt to
do so. Here are some known pitfalls:
o Since a library cannot be modified, no library command may be
the target of a STO or PUT operation.
o XLIB names are not usable in all contexts in which global
names are valid arguments. This can cause constructs that
reference a named object to fail. For example,
'A' 5 GETI
where A is a list will not work when A is converted to an
XLIB name. Instead use
'A' EVAL 5 GETI
or better yet
A 5 GETI
XLIB names are not valid as formal variables in algebraics,
or as the independent variable for plotting or solving.
Names intended to be used as such should be declared as
global using $VARS or the -v option.
o ->STR applied to a global name that is converted to a
``hidden'' library command (see $HIDDEN) returns a null
string.
o Embedded directories (entered as DIR...END) within lists and
programs are not translated except for their first object.
-5-
1.3 Library Creation
The process of library creation and activation can be summarized
as follows.
Item: 752 by vervalin at AUSTIN.LOCKHEED.COM
Author: Documentation by Paul Vervalin; BRIX by Andreas Gustafsson.
Subj: BRIX decoded
Keyw: CHIP48 BRIX
Date: Sat Sep 15 1990 09:57
Below is a detailed description of the BRIX game that is run with the CHIP48
interpreter. I hope this helps others when writing programs using CHIP48.
All of this is hand typed so please forgive me if there are any typos.
Happy programming!!
register contents
---------------------------------------,
to a variable in any convenient directory.
5. Recall the library object from the variable to which it was
transferred, and then store it in a RAM port (:n:x STO,
where n is the port number, and x is any number). After
storing the library, you can purge the original copy in the
variable to save memory.
6. Turn the HP 48 off, then on. This adds the new library to
the system library table, and gives the library a chance to
execute its own configuration program, if any. (The HP 48
will execute a system halt automatically at this stage, so
you should save any stack objects or PICT first if you wish
to recover them.) The LIBRARY menu will now contain a menu
entry labeled with the library's ID number in the PORTn
submenu.
7. Activate the directory in which you wish the library's
commands to be accessible, then execute nnn ATTACH, where
nnn is the library ID. Any number of libraries can be
attached to the HOME directory; subdirectories may have one
library attached to each. The main LIBRARY menu will now
contain a menu key labeled by the library's title.
To remove a library, activate its associated directory and execute
nnn DETACH. Then execute :n:ID PURGE to remove the library from
port n. (You will notice a brief jump in the display when you
execute the PURGE. This is normal and harmless.)
-6-
2. Instructions
(In the following, <bold> text represents user-supplied text. Text
appearing in brackets [ ] denotes optional entries. In actual
entries, the [ ] should not be used.)
Syntax:
USRLIB [-options] <dirfile> [ <libfile> [ <sumfile> ] ]
<dirfile> is the name of the source file, which must contain a
binary image of an HP48 directory or a backup object
containing a directory.
<Libfile> is a file to contain the output library object.
<sumfile> This is a textual summary of the names that were
translated. The following information is given for each
object: user name, type, offset into the <libfile> file,
XLIB numbers, whether it can be used in an algebraic,
and whether it is visible.
Similarly, a list of message numbers and messages and a
summary of the space requirements is given.
<Sumfile> and the optional <listfile> (see OPTIONS below) may be
redirected to stdout by using '-' for the output file name.
2.1 Options
The following options may be included in the USRLIB command line:
-d<listfile> <listfile> will contain a text listing of the contents
of each object in the input directory.
-h<header> Use <header> for the library object header (for file
transfer).
-l<listfile> <listfile> will contain a text listing of the contents
of each object in the output library. Occurrances of
"ID'name'<--" indicate translation of an name (ID)
into an XLIB or a message table reference.
-r<romid> Set decimal Library ID (see $ROMID above).
-7-
-t<title> Use <title> for the library title (see $TITLE above).
-v<name> Declare <name> as a RAM variable name (see $VARS above).
2.2 Restrictions
1. The total library output file cannot be larger than 128K
bytes.
2. Message strings must be less than 64K bytes each.
2.3 Error Messages
In the following, words shown in parentheses within the quoted
error messages represent values that indicate source-specific
quantities. (path) represents the path within the source directory
to the variable causing the error, in the form name1/name2/... ,
where the names are the subdirectoy names (on the HP 48SX, the
path would be a list { name1 name2 ... }).
2.3.1 General Errors
"Cannot allocate memory" --memory is constantly being allocated
for various compiler needs.
"Unexpected EOF on input" --EOF was hit when more nibbles were
expected.
"Can't malloc for decomp" --can't get memory to create decompile
information.
2.3.2 Initialization/First Pass Errors
"USRLIB: Cannot open" --The source file can not be opened.
"USRLIB: - not legal for input" -- "-" (stdin) can't be used for
input.
"Cannot alloc 128K bytes for image" --Insufficient memory for the
library image.
"ROMID must be in range 769 - 1792"
"Must have either -r romid or $ROMID" --no library ID was
specified.
-8-
"Need either BAK of a directory or a directory"
"BAK object does not contain directory"
"Directory is empty"
"Object is not a string: (path)/$TITLE"
The next three messages may occur when ROMID is specified in the
variable $ROMID.
"Illegal Real value for (path)/$ROMID: (value)"
"Illegal Binary value for (path)/$ROMID: (value)"
"Object not Real or Binary: (path)/$ROMID"
The next two messages may occur when a $CONFIG variable (or two)
are specified.
"Object not program: (path)/$CONFIG"
"$CONFIG redefined: (path)/$CONFIG"
The next two messages may occur any time a string (variable name
or message) isread.
"Variable name or message too long (>65535)"
"Out of memory: trying to malloc for string"
The next three messages may occur when a name list is being read.
The $MESSAGE, $VISIBLE, $HIDDEN, and $VARS variables are all name
lists.
"Object is not a list: (path)/name"
"Non-ID found in list: (path)/name"
"Out of memory: (path)/name"
The next three messages occur during creation of and addition to
internal name tables, and are variations of insufficient memory
errors.
"Cannot malloc id table"
"Cannot malloc id entry: (path)/(name)"
"Cannot malloc id entry: (path)/(name)"
-9-
2.3.3 Interim/Second Pass Errors
"Message object not found: (name)"
"Loss of object synchronism between passes: (path)/(name)" --
(path)/(name) is replaced with the object where out-of-sync was
discovered.
"Name must not exceed 16 characters: (path)/(name)" --library
object names are limited to 16 characters.
"Keyword cannot resolve to a directory: (path)/(name)" --
Subdirectory names cannot be included in other directory objects'
definitions.
The next two messages may occur as message objects (indicated in
the $MESSAGE list) are being converted into a message table.
"Message object is not a string: (path)/(name)"
"Multiple definitions for message (path)/(name)"
2.3.4 Clean-up/Write File Phase Errors
"Library image length is 0.
LIB FILE NOT WRITTEN!"
"Max image size is 256K nibbles ... image is (value) nibbles.
LIB FILE NOT WRITTEN!"
"Unsucessful write to library file" --unknown error writing to library file.
-10-
